Cargo

Documentation

  • cargo doc

    • Builds the documentation for the local package and all dependencies. The output is placed in target/doc  in rustdoc’s usual format.

Packages

  • It's a bundle of one or more crates that provides a set of functionality.

  • A package contains a Cargo.toml  file that describes how to build those crates.

Creating a Package

  • cargo new NAME

    • Compiles to a binary.

    • main.rs  is used as the package root.

  • cargo new --lib NAME

    • Compiles to a library.

    • lib.rs  is used as the package root.

Compilation

  • cargo build

    • Compile and generate an executable.

  • ./executable_name

    • Run the executable.

  • cargo check

    • Compile without generating an executable.

    • Faster than cargo build .

  • cargo run

    • Compile, generate, and run the executable.

Cargo.toml

  • .

Cargo.lock

  • When you build a project for the first time, Cargo figures out all the versions of the dependencies that fit the criteria and then writes them to the Cargo.lock  file. When you build your project again, Cargo will see that the Cargo.lock  file exists and will use the versions specified there rather than figuring out versions again. This lets you have a reproducible build automatically. In other words, your project will remain at 0.8.5 until you explicitly upgrade, thanks to the Cargo.lock  file.

  • Because the Cargo.lock  file is important for reproducible builds, it’s often checked into source control with the rest of the code in your project.

Crates

  • It's a tree of modules.

Binary Crate

  • Must have a function called main  that defines what happens when the executable runs.

Library Crate

  • Doesn't have a main  function, and they don’t compile to an executable.

  • They define functionality intended to be shared with multiple projects.

  • Usually, when people say “crate”, they mean 'library crate'.

Crate Root

  • The crate root  is a source file that the Rust compiler starts from and makes up the root module of your crate.

    • Usually symbolized by main.rs  or lib.rs , depending if the Package is bin or lib.

  • Every package needs a Crate Root.

  • In the crate root file, you can declare new modules, like mod garden; .

  • The compiler will look for the module’s code in these places:

    • Inline, within curly brackets that replace the semicolon following mod garden

    • In the file src/garden.rs

    • In the file src/garden/mod.rs

Submodules

  • In any file other than the crate root, you can declare submodules. For example, you might declare mod vegetables;  in src/garden.rs .

  • The compiler will look for the submodule’s code within the directory named for the parent module in these places:

    • Inline, directly following mod vegetables , within curly brackets instead of the semicolon

    • In the file src/garden/vegetables.rs

    • In the file src/garden/vegetables/mod.rs

Modules and Use

  • Let you control organization, scope, and path privacy 

mod back_of_house {
    pub struct Breakfast {
        pub toast: String,
        seasonal_fruit: String,
    }

    impl Breakfast {
        pub fn summer(toast: &str) -> Breakfast {
            Breakfast {
                toast: String::from(toast),
                seasonal_fruit: String::from("peaches"),
            }
        }
    }
}

pub fn eat_at_restaurant() {
    // Order a breakfast in the summer with Rye toast
    let mut meal = back_of_house::Breakfast::summer("Rye");
    // Change our mind about what bread we'd like
    meal.toast = String::from("Wheat");
    println!("I'd like {} toast please", meal.toast);

    // The next line won't compile if we uncomment it; we're not allowed
    // to see or modify the seasonal fruit that comes with the meal
    // meal.seasonal_fruit = String::from("blueberries");
}
Super

  • Refers to the parent module.

Paths

  • A way of naming an item, such as a struct, function, or module.